<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Pavel Jareš on Medium]]></title>
        <description><![CDATA[Stories by Pavel Jareš on Medium]]></description>
        <link>https://medium.com/@pavel.jares?source=rss-c3192fcaafa6------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*f5N6zDOxcXAg6Eb7KA-jGQ.jpeg</url>
            <title>Stories by Pavel Jareš on Medium</title>
            <link>https://medium.com/@pavel.jares?source=rss-c3192fcaafa6------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 15:48:55 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@pavel.jares/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[AT-TLS Aware Mode in a Mainframe Java Application]]></title>
            <link>https://medium.com/@pavel.jares/at-tls-aware-mode-in-a-mainframe-java-application-f31d64e8a0fb?source=rss-c3192fcaafa6------2</link>
            <guid isPermaLink="false">https://medium.com/p/f31d64e8a0fb</guid>
            <dc:creator><![CDATA[Pavel Jareš]]></dc:creator>
            <pubDate>Mon, 23 May 2022 07:15:22 GMT</pubDate>
            <atom:updated>2022-05-23T07:15:22.797Z</atom:updated>
            <content:encoded><![CDATA[<p>In the previous two articles of this series, <a href="https://medium.com/modern-mainframe/at-tls-for-the-modern-mainframe-java-applications-7a69de53b7ad">AT-TLS for the Modern Mainframe Java Applications</a> and <a href="https://medium.com/modern-mainframe/at-tls-configuration-for-the-modern-mainframer-e26f72f0f9bb">AT-TLS Configuration for Mainframe Java Applications</a> the story of AT-TLS for Mainframe Java applications took shape. Going through the introduction and now that a server configuration is available, it is time to present what runtime handling is needed for the proper implementation of the AT-TLS Aware Mode by the modern mainframer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*U4ihKGVPQvUkRwD0Rzixag.jpeg" /></figure><p>The use of AT-TLS aware mode requires native code to interact with the core z/OS services. Luckily, it can be found readily available in this Broadcom <a href="https://github.com/zowe/common-java/tree/master/attls">source code contribution</a> to the Zowe project. The native code should focus on a few aspects: to effectively connect sessions with the client’s code and synchronize multiple calls for details during a single request.</p><p>Requests use sockets that are identified by a number (ID), which matches their corresponding file descriptor in the operating system. This ID is used to communicate with the <a href="https://www.ibm.com/docs/en/zos/2.5.0?topic=functions-ioctl-control-device">IOCTL service</a> responsible for fetching information about AT-TLS states per each socket. The ID remains hidden inside the web server, e.g. Tomcat, and it usually remains inaccessible from Java code.</p><p>A simple strategy to avoid multiple system calls is to ensure those calls are made only once. The essential information necessary, in this case, would be the current state of the channel (secure vs. insecure) and the user ID (in the case of client certificate authentication). From the perspective of the native code library, a Data Transfer Object (DTO) could be used to collect the information once and then store it for future reference. The <a href="https://github.com/zowe/common-java/blob/c70e379bd1f831a6c6c6f8302b4883bcb7242cfc/attls/README.md#implementation">Zowe AT-TLS library</a> solves the problem by storing IDs and binary data inside a class named `AttlsContext`, accessible via `InboundAttls`. It uses `ThreadLocal` to map the right AT-TLS context with the calling thread.</p><p>Below is a minimalistic example of a java wrapper class that uses ThreadLocal (note that the native library is loaded in a static initialization block the first time the application uses the class):</p><pre>package com.mycompany;<br><br>import lombok.Getter;<br><br>public class Attls {<br><br>    private static final ThreadLocal&lt;AttlsInfo&gt; threadToAttls = new ThreadLocal&lt;&gt;();<br><br>    static {<br>        System.loadLibrary(&quot;attls&quot;);<br>    }<br><br>    public static void init(int socketId) {<br>        threadToAttls.set(new AttlsInfo(socketId));<br>    }<br><br>    public static AttlsInfo get() {<br>        return threadToAttls.get();<br>    }<br><br>    public static void dispose() {<br>        threadToAttls.remove();<br>    }<br><br>    @Getter<br>    public static class AttlsInfo {<br><br>        private final int socketId;<br>        private boolean secured;<br>        private String userId;<br><br>        AttlsInfo(int socketId) {<br>            this.socketId = socketId;<br>            fetchData(socketId);<br>        }<br><br>        private native void fetchData(int socketId);<br><br>    }<br><br>}</pre><p>The base class AttlsInfo is instantiated with a socket ID parameter for each request and during application initialization. It is responsible for calling the native function `fetchData`, which would call the IOCTL service and would fetch two things: secure connection status and user ID (in case the request is signed by a client certificate). This wrapper class would be calling native code. To generate the interface (header file) you can use the following command: `$JAVA_HOME/bin/javah -jni com.mycompany.Attls`. The resulting code is then saved in attls.h. The method definition could be copied into the attls.c file. That is the required step before writing native code.</p><p>The final implementation may require some adjustments as shown in the example below:</p><pre>#include &quot;attls.h&quot;<br><br>#include &lt;resolv.h&gt;<br>#include &lt;ezbztlsc.h&gt;<br><br><em>// this pragma generates string value encoded in ASCII<br></em>#if defined(__IBMC__) || defined(__IBMCPP__)<br>#pragma convert(819)<br>#endif<br><br>const char *ILLEGAL_STATE_EXCEPTION = &quot;java/lang/IllegalStateException&quot;;<br>const char *SECURED = &quot;secured&quot;;<br>const char *USER_ID = &quot;userId&quot;;<br>const char *SIGNATURE_STRING = &quot;Ljava/lang/String;&quot;;<br>const char *SIGNATURE_BOOLEAN = &quot;Z&quot;;<br><br>#if defined(__IBMC__) || defined(__IBMCPP__)<br>#pragma convert(0)<br>#endif<br><br>JNIEXPORT void JNICALL Java_com_mycompany_Attls_00024AttlsInfo_fetchData (JNIEnv *env, jobject obj, jint socketId)<br>{<br>   struct TTLS_IOCTL ioc = {0};<br><br>   <em>// fulfill request<br>   </em>ioc.TTLSi_Ver = TTLS_VERSION1;<br>   ioc.TTLSi_Req_Type = TTLS_QUERY_ONLY;<br><br>   <em>// call ioctl<br>   </em>int rc = ioctl(socketId, SIOCTTLSCTL, (char*) &amp;ioc);<br><br>   <em>// if ioctl returns an error throw exception<br>   </em>if (rc &lt; 0) {<br>       char message[256] = {0};<br>       snprintf(message, 255, &quot;Cannot obtain AT-TLS data about socket ID=%. Return code: %d&quot;, socketId, rc);<br>     __etoa(message);<br>       jclass exception = (*env) -&gt; FindClass(env, ILLEGAL_STATE_EXCEPTION);<br>       (*env) -&gt; ThrowNew(env, exception, message);<br>       return;<br>   }<br><br>   <em>// get class of AttlsInfo<br>   </em>jclass clazz = (*env) -&gt; GetObjectClass(env, obj);<br><br>   <em>// check if connection is secured and store the flag in AttlsInfo<br>   // 1 = non-secure, 2 = handshake in progress, 3 = secure<br>   </em>jfieldID secured = (*env) -&gt; GetFieldID(env, clazz, SECURED, SIGNATURE_BOOLEAN);<br>   (*env) -&gt; SetBooleanField(env, obj, secured, (jboolean) (ioc.TTLSi_Stat_Conn == 3));<br><br>   <em>// get userId, convert to ASCII and set into AttlsInfo<br>   </em>jfieldID userId = (*env) -&gt; GetFieldID(env, clazz, USER_ID, SIGNATURE_STRING);<br>   __etoa(ioc.TTLSi_UserID);<br>   (*env) -&gt; SetObjectField(env, obj, userId, (*env) -&gt; NewStringUTF(env, ioc.TTLSi_UserID));<br>}</pre><p>This sample code is quite self-explanatory. It starts with declaring the required text literals so they are compatible with JNI, which mandates the use of ASCII encoding. The code continues with the initialization of the IOCTL structure, in the concrete example, it resets all fields and sets the AT-TLS version and request types. After the IOCTL call is executed and no error is detected, the program would fetch the data and store it in the `AttlsInfo` class transcoding the EBCDIC strings to ASCII encoding in the process.</p><p>Building and linking the native code library can be done with the following commands:</p><pre>xlc -W &quot;c,langlvl(extended),dll,xplink,exportall&quot; -qsearch=$JAVA_HOME/include -qsource -g  -c -qlist=libattls.cpp.lst -o attls.o attls.c</pre><pre>xlc++ -W &quot;l,lp64,dll,dynam=dll,xplink,map,list&quot; -g -qsource -o libattls.so $JAVA_HOME/bin/j9vm/libjvm.x attls.o &gt; libattls.bind_64.lst</pre><p>The produced binary file would need to have its accessors changed to be executable and program-controlled:</p><pre>extattr +p libattls.co<br>chmod a+x libattls.so</pre><p>Finally, the file location should be added to LIBPATH. Note that in Java, the library is loaded just by the name “attls”; the prefix “lib” and suffix “.so” are added automatically by the JVM (see. <a href="https://medium.com/p/5b5277360a12">Dynamic Linkage to a z/OS Native Library in Java</a>).</p><p>The entire functionality of AT-TLS revolves around a socket ID; it is required to obtain this value at the beginning of each request. The use of an embedded Tomcat server is the one used in the example below but the principle is the same for any other web server.</p><pre>@Bean<br>public&lt;T&gt; TomcatConnectorCustomizer attlsOnEmbededTomcat() {<br>    return connector -&gt; {<br>        try{<br>            ProtocolHandler protocolHandler=connector.getProtocolHandler();<br>    <br>            Field handlerField=AbstractProtocol.class.getDeclaredField(&quot;handler&quot;);<br>            handlerField.setAccessible(true);<br>            AbstractEndpoint.Handler&lt;T&gt; handler=(AbstractEndpoint.Handler&lt;T&gt;) handlerField.get(protocolHandler);<br>    <br>            handler=new AttlsHandler&lt;&gt;(handler);<br>    <br>            Method methodHandler=AbstractProtocol.class.getDeclaredMethod(&quot;getEndpoint&quot;);<br>            methodHandler.setAccessible(true);<br>            AbstractEndpoint&lt;T,?&gt; endpoint=(AbstractEndpoint&lt;T, ?&gt;) methodHandler.invoke(protocolHandler);<br>            endpoint.setHandler(handler);<br>    <br>            handlerField.set(protocolHandler, handler);<br>        } catch(Exception e) {<br>            throw new IllegalStateException(&quot;Cannot prepare AT-TLS handler&quot;,e);<br>        }<br>    };<br>}</pre><p>This sample code obtains the original handler, customizes it as a delegator, and then sets it back to be used with the same interface and be able to recall all methods of the original instance. The next step would be to obtain the socket ID, initialize the AT-TLS object capable of fetching all necessary data, call the original method and then clean up to dispose of the AT-TLS state.</p><pre>@RequiredArgsConstructor<br>class AttlsHandler&lt;T&gt; implements AbstractEndpoint.Handler&lt;T&gt; {<br><br>    @Delegate(excludes = Proccess.class)<br>    private final AbstractEndpoint.Handler&lt;T&gt; original;<br><br>    private Field fdField;<br>    <em>/**<br>     * Methods take file description from all known sockets<br>     * @param socket implementation of socket in Tomcat<br>     * @return file descriptor value<br>     */<br>    </em>private int getFd(SocketChannel socket) {<br>        if (fdField == null) {<br>            try {<br>                fdField = socket.getClass().getDeclaredField(&quot;fdVal&quot;);<br>                fdField.setAccessible(true);<br>            } catch (IllegalArgumentException | IllegalStateException | NoSuchFieldException e) {<br>                throw new IllegalStateException(&quot;Cannot find file descriptor (socket ID)&quot;, e);<br>            }<br>        }<br>        try {<br>            return fdField.getInt(socket);<br>        } catch (IllegalAccessException e) {<br>            throw new IllegalStateException(&quot;Cannot obtain file descriptor (socket ID)&quot;, e);<br>        }<br>    }<br><br>    <em>/**<br>     * This method handles processing of each request. At first create AT-TLS context, the process and on the end<br>     * dispose the context.<br>     * @param socketWrapperBase describing socket (see Tomcat implementation)<br>     * @param status status of socket (see Tomcat implementation)<br>     * @return new status of socket (see Tomcat implementation)<br>     */<br>    </em>public SocketState process(SocketWrapperBase socketWrapperBase, SocketEvent status) {<br>        NioChannel nioChannel = (NioChannel) socketWrapperBase.getSocket();<br>        Attls.init(getFd(nioChannel.getIOChannel()));<br>        try {<br>            return original.process(socketWrapperBase, status);<br>        } finally {<br>            Attls.dispose();<br>        }<br>    }<br><br>    interface Proccess {<br><br>        &lt;T&gt; SocketState process(SocketWrapperBase&lt;T&gt; socket, SocketEvent status);<br><br>    }<br><br>}</pre><p>The difference between this custom implementation and the use of the Zowe library is about the InboundAttls class instance of Attls (as shown in the previous paragraph).</p><pre>InboundAttls.init(getFd(nioChannel.getIOChannel()));<br>try {<br>    return original.process(socketWrapperBase, status);<br>} finally {<br>    InboundAttls.dispose();<br>}</pre><p>In both cases, the result is an object accessible from any place in the code (except for new threads), capable of retrieving information about the AT-TLS state (`Attls.get()`, `InboundAttls.get()`, etc.).</p><p>The most important part of this implementation is the verification if the connection is secured or not. This is now possible to do through a servlet filter that calls `Attls.get().isSecured()` or `InboundAttls.getStatConn() == SECURE` for the Zowe library. If the connection is not secured, the processing should be interrupted as soon as possible (throwing an exception should be enough).</p><p>Co-authored by <a href="https://medium.com/u/80a1656b4edd">Boris Petkov</a></p><p>Attachment: <a href="https://github.com/pj892031/attls">The source code</a></p><p>Note: All AT-TLS constants could be found in <a href="https://www.ibm.com/docs/en/zos/2.5.0?topic=ioctl-siocttlsctl-xc038d90b">IBM documentation</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f31d64e8a0fb" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Dynamic Linkage to a z/OS Native Library in Java]]></title>
            <link>https://medium.com/@pavel.jares/dynamic-linkage-to-a-z-os-native-library-in-java-5b5277360a12?source=rss-c3192fcaafa6------2</link>
            <guid isPermaLink="false">https://medium.com/p/5b5277360a12</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[dynamic-link-library]]></category>
            <category><![CDATA[native-code]]></category>
            <category><![CDATA[jni]]></category>
            <category><![CDATA[mainframe]]></category>
            <dc:creator><![CDATA[Pavel Jareš]]></dc:creator>
            <pubDate>Fri, 08 Apr 2022 12:29:33 GMT</pubDate>
            <atom:updated>2022-04-08T12:29:33.028Z</atom:updated>
            <content:encoded><![CDATA[<p>To access core z/OS features from a Java mainframe application, one would need to consider the use of the <a href="https://developer.ibm.com/articles/j-jni/">Java Native Interface</a> framework. A few examples of such need could be found in the interaction with the built-in z/OS Communication Server component named AT-TLS (see: <a href="https://medium.com/modern-mainframe/at-tls-for-the-modern-mainframe-java-applications-7a69de53b7ad">AT-TLS for the Modern Mainframe</a>) or the direct interaction with the z/OS security managers such as RACF, TopSecret, ACF/2, etc. This article will try to narrow down the minimum requirements on how to link with native libraries, how to package, deliver and deploy the resulting programs easily and concisely.</p><p><strong><em>Note</em></strong><em>: all the code examples below can be found in </em><a href="https://github.com/pj892031/jniDynamicLoading"><em>this public repository</em></a><em>.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Jr6ipk6q_9eS4K7k" /></figure><p>Firstly, a collection of needed libraries is required. Putting them all in a folder, set their <em>executable</em> and <em>program-controlled</em> (z/OS only) flags, and add them to the library path environment variable. The following Unix commands will do the trick:</p><pre>extattr +p *.so # only for z/<em>OS<br></em>chmod a+x *.so</pre><p>There are two ways to propagate the information about native libraries’ location to the Java runtime: one is via the system variable `LIBPATH`, and the other is via the application argument `-Djava.library.path`. Both serve the same purpose but the application argument has precedence over the environment variable. Below is a list of commonly used z/OS paths where other libraries (e.g. JZos, IRR, etc.) could be found. Those directories are often added to the application library path arguments or the environment variable:</p><ul><li>/lib</li><li>/usr/lib</li><li>${JAVA_HOME}/bin</li><li>${JAVA_HOME}/lib/s390x</li><li>${JAVA_HOME}/lib/s390x/j9vm</li><li>${JAVA_HOME}/bin/classic</li></ul><p><strong><em>Note</em></strong><em>: The library paths could be different on a particular installation.</em></p><p>The next step is to load the library into memory, which could be done in two ways. The more straightforward way is to load the library by specifying the absolute path and exact filename using the method <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#load-java.lang.String-"><em>`java.lang.System#load`</em></a>. The second and preferred way is to use the method <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#loadLibrary-java.lang.String-"><em>`java.lang.System#loadLibrary`</em></a> with the library name. The filename is then derived from the library name by adding the `lib` prefix and using the `.so` or `.dll` file extension, depending on the platform.</p><pre><em>// using absolute path<br></em>static {<br>    System.<em>load</em>(&quot;/z/user/libfeature.so&quot;);<br>}<br><br><em>// using library name<br></em>static {<br>    System.<em>loadLibrary</em>(&quot;feature&quot;);<br>}</pre><p>This, unfortunately, is not everything needed when dealing with dynamically loaded libraries. It may be enough during the development phase but there are more details needed before a complete release of the software can be completed. The first consideration is to determine the platforms on which the application would be expected to run. More frequently, multiple platforms will be supported: z/OS, Linux, Unix, 64-bit, 32-bit, 31-bit (z/OS), etc.</p><p>To allow the application to run on multiple platforms off z/OS it is necessary to create two implementations with the same interface and a factory method (or a similar approach). The decision of which implementation to use should be based on the system property `os.name`. In z/OS it returns the value “z/OS’’.</p><pre>interface NewFeature {<br><br>    void doStuff();<br><br>}<br><br>class NewFeatureZos implements NewFeature {<br><br>    @Override<br>    public native void doStuff();<br><br>}<br><br>class NewFeatureDummy implements NewFeature {<br><br>    @Override<br>    public void doStuff() {<br>        System.<em>out</em>.println(&quot;Platform not supported.&quot;);<br>    }<br><br>}<br><br>@lombok.experimental.UtilityClass<br>class Factory {<br><br>    public NewFeature getNewFeature() {<br>        if (&quot;z/OS&quot;.equals(System.<em>getProperty</em>(&quot;os.name&quot;))) {<br>            return new NewFeatureZos();<br>        } else {<br>            return new NewFeatureDummy();<br>        }<br>    }<br><br>}</pre><p>The packaging of the application should contain native binaries for each combination of platform and operating system that is planned to be supported. During runtime, the application would need to decide which library file to load based on system properties, such as the `<em>com.ibm.vm.bitmode` </em>available on z/OS, which returns “32” for 31-bit or “64” for 64-bit architecture. Other JDKs use another property named `sun.arch.data.model`. An updated implementation of the factory class may look something like this:</p><pre>class NewFeatureZos implements NewFeature {<br><br>    static {<br>        if (&quot;32&quot;.equals(System.<em>getProperty</em>(&quot;com.ibm.vm.bitmode&quot;))) {<br>            System.<em>load</em>(&quot;feature-31&quot;);<br>        } else{<br>            System.<em>load</em>(&quot;feature-64&quot;);<br>        }<br>    }<br><br>    @Override<br>    public native void doStuff();<br><br>}</pre><p><strong><em>Note:</em></strong><em> The application packaging must include both files `libfeature-31.so` and `libfeature-64.so`.</em></p><p>With the recent announcement of JDK 11 on z/OS (aka <a href="https://www.ibm.com/support/pages/java-sdk-downloads-version-110">IBM Semeru Runtime Certified Edition, Version 11</a>), comes the possibility of loading a 31-bit library under 64-bit JDK, which makes it possible to release an application with fewer versions of its native dependencies. Nevertheless, delivering binaries for each architecture is still preferred mainly for performance reasons but also for backward compatibility with JDK 8.</p><p>Besides packaging, the application’s life cycle includes release and deployment. From a native library point of view, the binary files should be included in a PAX (or some of its alternatives) and an installation script should contain the logic for deploying, modifying, and running the program with proper configuration (e.g. library paths). It is more difficult when the libraries are provided by a 3rd party in a bundled JAR file, in which case the JAR would need to be extracted before including them in a release. A change in any of the native dependencies of a Java application would require repeating the whole release process.</p><p>An experienced developer would always consider other options of delivering their application to its users, more concretely for a java application, packaging the program in a JAR file could always be an alternative. The question here would be if packaging the native libraries and loading them on request would be possible. If it is, then bundling the native libraries will definitely save developers time in the release process. There is one specifying thing in z/OS to do before and it is that native libraries should be program-controlled on the platform. To set this flag, the application user requires `READ` access to the `BPX.FILEATTR.PROGCTL` resource in the `FACILITY` class.</p><pre>@lombok.experimental.UtilityClass<br>class NativeLibraryUtils {<br><br>    <em>/**<br>     * Collection of a loaded file to avoid loading<br>     * the same library multiple times<br>     */<br>    </em>private final Set&lt;String&gt; <em>loaded </em>= new HashSet&lt;&gt;();<br><br>    private File extract(String filename) {<br>        <em>// create a copy of library in the temporary folder<br>        </em>File libFile;<br>        try (InputStream is = <br>            NativeLibraryUtils.class.getResourceAsStream(filename)<br>        ) {<br>            libFile = File.createTempFile(filename, &quot;.so&quot;);<br>            try (OutputStream os = new FileOutputStream(libFile)) {<br>                IOUtils.copy(is, os);<br>            }<br>        } catch (IOException ioe) {<br>            throw new IllegalStateException(<br>                &quot;Could not load native library `&quot; + filename + &quot;`&quot;,<br>                ioe<br>            );<br>        }<br><br>        <em>// change file to be executable<br>        </em>libFile.setExecutable(true);<br>        <em>// change file to be program-controlled<br>        // this step is required only for z/OS<br>        </em>FileAttribute.setProgramControlled(<br>            libFile.getAbsolutePath(), true<br>        );<br><br>        <em>// clean up file after application will be stopped<br>        </em>libFile.deleteOnExit();<br><br>        return libFile;<br>    }<br><br>    private void load(String fileName) {<br>        <em>// check if the file has not been loaded yet, if not load it<br>        </em>synchronized (NativeLibraryUtils.class) {<br>            if (!<em>loaded</em>.contains(fileName)) {<br>                File file = <em>extract</em>(fileName);<br>                System.<em>load</em>(file.getAbsolutePath());<br>                <em>loaded</em>.add(fileName);<br>            }<br>        }<br>    }<br><br>    public void loadLibrary(String libraryName) {<br>        <em>// construct name of file<br>        </em>StringBuilder sb = new StringBuilder();<br>        sb.append(&quot;/lib/&quot;).append(libraryName);<br>        if (&quot;32&quot;.equals(System.<em>getProperty</em>(&quot;com.ibm.vm.bitmode&quot;))) {<br>            sb.append(&quot;-31&quot;);<br>        } else {<br>            sb.append(&quot;-64&quot;);<br>        }<br>        sb.append(&quot;.so&quot;);<br><br>        <em>// load the library<br>        load</em>(sb.toString());<br>    }<br><br>}</pre><p>In the example above it can be seen that the class of libraries functions also dynamically detects if they have been loaded or not. This permits multiple instances of this class to be used in different parts of the Java application without conflicts. The class that implements the native methods’ interface can now be simplified to just this:</p><pre>class NewFeatureZos implements NewFeature {<br><br>    static {<br>        NativeLibraryUtils.loadLibrary(&quot;feature&quot;);<br>    }<br><br>    @Override<br>    public native void doStuff();<br><br>}</pre><p>At this moment everything is handled in the utils implementation and the handling of the native libraries remains behind the scenes. The library path is no longer necessary either since it is only used to include the binaries in the JAR file, package, and release it — simple and clean.</p><p>Co-authored by <a href="https://medium.com/u/80a1656b4edd">Boris Petkov</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5b5277360a12" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AT-TLS Configuration for the Modern Mainframer]]></title>
            <link>https://medium.com/modern-mainframe/at-tls-configuration-for-the-modern-mainframer-e26f72f0f9bb?source=rss-c3192fcaafa6------2</link>
            <guid isPermaLink="false">https://medium.com/p/e26f72f0f9bb</guid>
            <category><![CDATA[ibm-z]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[mainframe]]></category>
            <dc:creator><![CDATA[Pavel Jareš]]></dc:creator>
            <pubDate>Tue, 16 Nov 2021 14:58:36 GMT</pubDate>
            <atom:updated>2022-05-23T07:16:49.876Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*W5evBgSeNngT7ofJhzoqjQ.jpeg" /></figure><p><a href="https://medium.com/modern-mainframe/at-tls-for-the-modern-mainframe-java-applications-7a69de53b7ad">AT-TLS for the Modern Mainframe Java Applications</a> is where this story began as an overview of the AT-TLS layer of the z/OS Communication Server. To understand the need for the configuration that is going to be presented here, it is essential to read the original article beforehand.</p><p>The AT-TLS configuration uses a format similar to JSON but not exactly. For example, labels should be without spaces and the number sign (#) is used for comments. The configuration could be structured to allow the reuse of different parts. For detailed information, check the <a href="https://www.ibm.com/docs/pl/zos/2.5.0?topic=ioctl-siocttlsctl-xc038d90b">AT-TLS policy statements</a>.</p><p>The first step to configure AT-TLS is defining a rule for the server-side, aka, the inbound call. This is where the network interface is specified via the local address setting. The `ALL` value can be used instead to listen on all interfaces and to specify only the port number, which can accept a fixed value or a range, e.g.: 12340–12345.</p><pre>TTLSRule ServerRule<br>{<br>  LocalAddr ALL<br>  RemoteAddr ALL<br>  LocalPortRange 12345<br>  Direction Inbound<br>  TTLSGroupActionRef ServerGroupAction<br>  TTLSEnvironmentActionRef ServerEnvironmentAction<br>  TTLSConnectionActionRef ServerConnectionAction<br>}</pre><p><strong>TTLSGroupAction</strong> could be used to define a setup according to the <a href="https://www.ibm.com/docs/en/zos/2.5.0?topic=11-operating-in-compliance-fips-140-2#opfips">FIPS standards</a>. In this case, for simplicity, it only enables the AT-TLS.</p><pre>TTLSGroupAction ServerGroupAction<br>{<br>  TTLSEnabled On<br>}</pre><p><strong>TTLSEnvironmentAction</strong> defines mainly the handshake parameters. Important thing is to set the role of the handshake and the certificate source, in this case, the rule `Keyring` as stated below.</p><pre>TTLSEnvironmentAction ServerEnvironmentAction<br>{<br>  HandshakeRole Server<br>  EnvironmentUserInstance 0<br>  TTLSEnvironmentAdvancedParmsRef EnvironmentAdvancedParms<br>  TTLSKeyringParmsRef Keyring<br>}</pre><p><strong>TTLSKeyringParams</strong> specifies the keyring in use that contains a private key for TLS as well as public certificates to verify remote connections (especially relevant for the outbound communication). The keyring is identified by its ID and does not require the user ID for the account under which the application runs.</p><pre>TTLSKeyringParms Keyring<br>{<br>  Keyring RINGID<br>}</pre><p><strong>TTLSEnvironmentAdvancedParms</strong> is used to define the level of protocols. In the example below, TLS 1.3 and 1.2 are left active and older protocols are disabled. The protocols could also be controlled by the application via the <strong>ApplicationControlled</strong> parameter, i.e. AT-TLS control mode as described in the <a href="https://medium.com/modern-mainframe/at-tls-for-the-modern-mainframe-java-applications-7a69de53b7ad">AT-TLS Overview</a> article. All that is necessary to enable it is to set the value to `On` here and in the <strong>TTLSConnectionAdvancedParms</strong>. Aware mode is activated automatically once AT-TLS is configured.</p><pre>TTLSEnvironmentAdvancedParms EnvironmentAdvancedParms<br>{<br>  ApplicationControlled Off<br>  Renegotiation Disabled<br>  SSLv2 Off<br>  SSLv3 Off<br>  TLSv1 Off<br>  TLSv1.1 Off<br>  TLSv1.2 On<br>  TLSv1.3 On<br>}</pre><p><strong>TTLSConnectionAction</strong>, in this case, is only used to collect the configuration defined as a separate block to be included in a `TTLSRule` rule.</p><pre>TTLSConnectionAction ServerConnectionAction<br>{<br>  HandshakeRole Server<br>  TTLSCipherParmsRef CipherParms<br>  TTLSConnectionAdvancedParmsRef ConnectionAdvancedParms<br>}</pre><p><strong>TTLSConnectionAdvancedParms</strong> is mainly used for certificates setup. The certificate label could be used to specify one, omitting it would select the default one in the keyring. It should be noted the <strong>ApplicationControlled</strong> value mentioned before and needed in case the controlling mode is desired.</p><pre>TTLSConnectionAdvancedParms ConnectionAdvancedParms<br>{<br>  ApplicationControlled Off<br>  ServerCertificateLabel sercCert<br>  SecondaryMap Off<br>}</pre><p><strong>TTLSCipherParms</strong> block can get a bit complicated as it is used to define ciphers to be used for communication. The list below is, by the time this article is published, TLS 1.3 compliant, however, this could change in the future. The full list of currently supported protocols can be found in the <a href="https://www.ibm.com/docs/en/zos/2.5.0?topic=statements-ttlscipherparms-statement">corresponding documentation</a>. It is important to double-check the spelling of the configuration values as a typo would disable a cipher and result in the cipher no longer being in use.</p><pre>TTLSCipherParms CipherParms<br>{<br>  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256<br>  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384<br>  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256<br>  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384<br>  V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384<br>  V3CipherSuites TLS_AES_128_GCM_SHA256<br>  V3CipherSuites TLS_AES_256_GCM_SHA384<br>  V3CipherSuites TLS_CHACHA20_POLY1305_SHA256<br>}</pre><p>To define an outbound configuration, many of the blocks described so far could be reused. It again could start with a <strong>TTLSRule</strong> very similar to the server rule with a difference being that it requires to indicate links to blocks with specific definitions and conditions to select a channel. A way to select an application on the server-side is ease — it is enough to only define the listening port. The outgoing calls, however, should be defined with better granularity. Specifying only the remote port or a range of ports may limit or alter the behavior of the client application as well. As an alternative, it might be more appropriate to define a job name instead or to use local ports.</p><pre>TTLSRule ClientRule<br>{<br>  RemotePortRange 12340-12345<br>  Jobname MYJOB*<br>  Direction Outbound<br>  TTLSGroupActionRef ClientGroupAction<br>  TTLSEnvironmentActionRef ClientEnvironmentAction<br>  TTLSConnectionActionRef ClientConnectionAction<br>}</pre><p>The rest of the outbound configuration is identical or very similar to the one for the inbound calls with one exception for the <strong>HandshakeRole</strong> value.</p><pre>TTLSEnvironmentAction ClientEnvironmentAction<br>{<br>  HandshakeRole Client<br>  TTLSKeyringParmsRef Keyring<br>  TTLSCipherParmsRef CipherParms<br>  TTLSEnvironmentAdvancedParmsRef EnvironmentAdvancedParms<br>}<br><br>TTLSGroupAction ClientGroupAction<br>{<br>  TTLSEnabled ON<br>}<br><br>TTLSConnectionAction ClientConnectionAction<br>{<br>  HandshakeRole Client<br>  TTLSCipherParmsRef CipherParms<br>  TTLSConnectionAdvancedParmsRef ConnectionAdvancedParms<br>}</pre><p>So far the base part of the AT-TLS configuration has been completed and is ready to be used. As an additional advanced setup, the configuration blocks could contain definitions of client certificates. Those could be defined separately for outbound and inbound calls. For the outbound calls, it is only necessary to define the <strong>CertificateLabel</strong> in the <strong>TTLSConnectionAdvancedParms</strong> block.</p><pre>TTLSConnectionAdvancedParms ConnectionAdvancedParms<br>{<br>  CertificateLabel clientCert<br>}</pre><p>The server-side or inbound advanced parameters could be slightly more complicated as they require to define one block for the handshake types (the server needs to confirm if a client certificate is accepted) and then define the client authentication type. <strong>ClientAuthType</strong> could have the value <strong>Required</strong> or <strong>Full</strong> if client certificates are optional. AT-TLS offers two more handshake types — <strong>PassThru</strong> and <strong>SAFCheck</strong>. More information can be found in the <a href="https://www.ibm.com/docs/en/zos/2.5.0?topic=statements-ttlsenvironmentadvancedparms-statement">official documentation from IBM</a>.</p><pre>TTLSEnvironmentAction ServerEnvironmentAction<br>{<br>  HandshakeRole ServerWithClientAuth<br>}</pre><pre>TTLSEnvironmentAdvancedParms EnvironmentAdvancedParms<br>{<br>  ClientAuthType Full<br>}</pre><pre>TTLSConnectionAction ServerConnectionAction<br>{<br>  HandshakeRole ServerWithClientAuth<br>}</pre><p>More rules could be defined to customize further the AT-TLS configuration and they could all be collected in a single USS file to then be set in a <a href="https://www.ibm.com/docs/en/zos/2.5.0?topic=reference-policy-agent-policy-applications">PAGENT</a>. The location of configuration is then set by the <a href="https://www.ibm.com/docs/en/zos/2.5.0?topic=statements-ttlsconfig-statement#ttlscon"><strong>TTLSConfig</strong> statement</a>. For the updated configuration to take effect, the <strong>MVS</strong> command should be executed. The <strong>/F PAGENT,REFRESH</strong> could be used to check what has been changed since the last execution, and <strong>/F PAGENT,UPDATE</strong> could be used to reload all rules. Using the update is considered a best practice to ensure all configuration changes are applied correctly. Depending on the network settings of the operating system, a restart of the TCP stack may be required too.</p><p>After all, definitions are drafted, it is necessary to verify them for syntax errors and misconfigurations. As a starting point, issuing the command `<a href="https://www.ibm.com/docs/en/zos/2.5.0?topic=tls-steps-diagnosing-problems">pasearch -t</a>` to find typos, invalid structures, and wrong configuration values. Once the syntax is corrected, studying the ‘Trace’ logs would be necessary for further troubleshooting. Log levels can be defined between 0 and 255 for each section of the AT-TLS setup — the higher the log level, the more detailed it would be. A value of 8 seems to enable enough traces for all possible configuration issues to be identified and it could be increased further for deeper troubleshooting. The errors with their specific <a href="https://www.ibm.com/docs/en/zos/2.5.0?topic=tls-return-codes">error codes</a> appear in the TCP IP and PAGENT logs. It is also good to know that the whole configuration could be done by z/OSMF, which is useful, especially when setting up only one system.</p><p>After following all the steps described above, the HTTP-enabled mainframe application would be accessible through the TLS protocol. This would be the first major milestone in this journey of leveraging the capabilities of AT-TLS, however, one should be cautious of the potential negative impact this environment could have on. For example, a simple misconfiguration or an accidental disabling of the AT-TLS would remove the security layer without warnings and would render all the network traffic plain and public. Of course, such situations have already been predicted and thought over with avoidance practices available that will be discussed in the next article of this series.</p><p>Co-authored by <a href="https://medium.com/u/80a1656b4edd">Boris Petkov</a></p><p>Attachment: <a href="https://github.com/pj892031/attls/blob/884da020921508f875c593c74b4e1f83dda7e39d/attls.txt">example of AT-TLS configuration</a></p><p>Further reading: <a href="https://medium.com/@pavel.jares/at-tls-aware-mode-in-a-mainframe-java-application-f31d64e8a0fb">AT-TLS Aware Mode in a Mainframe Java Application</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e26f72f0f9bb" width="1" height="1" alt=""><hr><p><a href="https://medium.com/modern-mainframe/at-tls-configuration-for-the-modern-mainframer-e26f72f0f9bb">AT-TLS Configuration for the Modern Mainframer</a> was originally published in <a href="https://medium.com/modern-mainframe">Modern Mainframe</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AT-TLS for the Modern Mainframe Java Applications]]></title>
            <link>https://medium.com/modern-mainframe/at-tls-for-the-modern-mainframe-java-applications-7a69de53b7ad?source=rss-c3192fcaafa6------2</link>
            <guid isPermaLink="false">https://medium.com/p/7a69de53b7ad</guid>
            <category><![CDATA[oz]]></category>
            <category><![CDATA[zowe]]></category>
            <category><![CDATA[mainframe]]></category>
            <category><![CDATA[broadcom]]></category>
            <category><![CDATA[attls]]></category>
            <dc:creator><![CDATA[Pavel Jareš]]></dc:creator>
            <pubDate>Fri, 01 Oct 2021 12:02:47 GMT</pubDate>
            <atom:updated>2021-12-08T14:41:51.282Z</atom:updated>
            <content:encoded><![CDATA[<p>This article offers an overview of the purpose and use of the AT-TLS, a z/OS Communication Server component, in Java applications on the mainframe. AT-TLS (Application Transparent — Transport Layer Security), also known as just TTLS (the original name), is a layer in z/OS Communication Server that can enable the use of HTTPS protocol for any application. Broadcom has invested significant R&amp;D time in exploring the topic and even contributed a <a href="https://github.com/zowe/common-java/tree/master/attls">Java library</a> to the <a href="https://www.zowe.org/">Zowe</a> project where we share the expertise we gained on this topic.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/873/1*51tYF2h0zoHBY_A8rbCYrw.png" /></figure><p>In essence, an HTTP or FTP application could be written without supporting the security version of the protocols and leave it to the operating system to upgrade it with the secured extension. This results in having just one layer and one definition of security parameters for multiple applications allowing for streamlined updates to security rules and follow-up on updated security policies. AT-TLS eliminates the need to individually update each program applying the same policy over and over again.</p><p>AT-TLS can be enabled for inbound calls, outbound calls, or for both directions. This is important since most of the time, system programmers operate on just part of the communication protocols that apply strictly to their area of responsibility. One should also keep in mind that the remote parts could be running on a different platform without z/OS.</p><p>One of the key features of AT-TLS is that it is transparent, this means the application only deals with the plain HTTP or FTP parts of the protocol. The header of the request is updated on the fly and thus it is impossible to determine which protocol in fact is being used. Certain details that would need to be considered for successful communication, for example, in the case of outbound calls, when an application with enabled AT-TLS calls a secured endpoint, the URL must indicate HTTP protocol. It is then updated to the secure version by the AT-TLS and the application remains unaware of this change by default.</p><p>Thinking about the above-described behavior where the application is not set to use the secure protocol, a few potential security breaches could come to one’s mind. One of the main questions would be how to avoid using open channels when the configuration of TLS is outside the application. A way to do that is to check the state of the channel that the AT-TLS reports as either disabled, basic, aware, or controlling.</p><p><strong>Disabled mode</strong> is clear — the application is not using AT-TLS, the feature is either not enabled or some critical configuration is missing. The mode is usually set when the application uses Java TLS libraries.</p><p><strong>Basic mode</strong> is used when the application implements either the HTTP or FTP protocols without TLS and the AT-TLS makes the bridge between the application and its remote access. This mode is the most straightforward way of using this technology requiring minimum AT-TLS configuration and ensuring that the application uses secured protocols everywhere</p><p><strong>Aware mode</strong> is probably the most important as it adds on top of the basic mode the possibility to check the state of the communication channel in use. By using native calls to the IOCTL service, an application can query the state of its AT-TLS (e.g.: enabled, disabled, configuration error, etc.). Some basic information about the protocol in use could also be fetched such as the user ID when a caller’s request is signed by a private key. The system would automatically find and map the request with the user that has signed it, thereby making it possible for the application to implement “password-less” authentication.</p><p><strong>Controlling mode</strong> offers further possibilities for managing during runtime the communication link and the protocols implemented. In this mode, the IOCTL service calls would allow the application to, for example, reset the cipher in use. A detailed description of this can be found in the <a href="https://www.ibm.com/docs/pl/zos/2.4.0?topic=ioctl-siocttlsctl-xc038d90b">IBM documentation</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZBpYZ0xOtOQOMXGwUxR4ew.png" /><figcaption>Request flow through AT-TLS</figcaption></figure><p>This very high-level overview of AT-TLS and how it can be implemented in a modern mainframe Java application. This can already be used as a starting point to draft designs and software architectures around it, nevertheless, further diving into the technical specifications with sample code snippets is needed to gather the necessary confidence to make use of this ingenious z/OS Communication Server component. Follow-up articles are duly needed and on their way to tell the story of configuring, interacting with the native z/OS libraries, setting up verification, authentication, filter and manage inbound and outbound calls.</p><p>Co-authored by <a href="https://medium.com/u/80a1656b4edd">Boris Petkov</a></p><p>Further reading: <a href="https://medium.com/modern-mainframe/at-tls-configuration-for-the-modern-mainframer-e26f72f0f9bb">AT-TLS Configuration for the Modern Mainframer</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7a69de53b7ad" width="1" height="1" alt=""><hr><p><a href="https://medium.com/modern-mainframe/at-tls-for-the-modern-mainframe-java-applications-7a69de53b7ad">AT-TLS for the Modern Mainframe Java Applications</a> was originally published in <a href="https://medium.com/modern-mainframe">Modern Mainframe</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>