directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From plusplusjia...@apache.org
Subject svn commit: r1726932 - in /directory/site/trunk: content/kerby/ content/kerby/user-guide/ templates/kerby/
Date Wed, 27 Jan 2016 01:49:34 GMT
Author: plusplusjiajia
Date: Wed Jan 27 01:49:34 2016
New Revision: 1726932

URL: http://svn.apache.org/viewvc?rev=1726932&view=rev
Log:
Update the info of apis in Kerby.

Added:
    directory/site/trunk/content/kerby/hierarchy.png   (with props)
    directory/site/trunk/content/kerby/kerby-asn1.mdtext
Modified:
    directory/site/trunk/content/kerby/user-guide.mdtext
    directory/site/trunk/content/kerby/user-guide/2-kerberos-library.mdtext
    directory/site/trunk/content/kerby/user-guide/2.2-kadmin.mdtext
    directory/site/trunk/content/kerby/user-guide/2.3-kdcserver.mdtext
    directory/site/trunk/content/kerby/user-guide/2.4-simplekdcserver.mdtext
    directory/site/trunk/templates/kerby/page.html

Added: directory/site/trunk/content/kerby/hierarchy.png
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/hierarchy.png?rev=1726932&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/site/trunk/content/kerby/hierarchy.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: directory/site/trunk/content/kerby/kerby-asn1.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/kerby-asn1.mdtext?rev=1726932&view=auto
==============================================================================
--- directory/site/trunk/content/kerby/kerby-asn1.mdtext (added)
+++ directory/site/trunk/content/kerby/kerby-asn1.mdtext Wed Jan 27 01:49:34 2016
@@ -0,0 +1,389 @@
+Title: Kerby ASN1
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+    .
+    http://www.apache.org/licenses/LICENSE-2.0
+    .
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+# Kerby ASN1
+
+### ASN1 hierarcy
+
+![](hierarchy.png)
+
+### A ASN1 parser with easy and simple API
+
+```
+// encoding
+Asn1Integer aValue = new Asn1Integer(8899);
+byte[] encoded = aValue.encode();
+
+// decoding
+byte[] contentToDecode = ...
+Asn1Integer decodedValue = new Asn1Integer();
+decodedValue.decode(contentToDecode);
+Integer value = decodedValue.getValue();
+```
+
+### Data-driven ASN1 encoding/decoding framework and parser
+
+With the following definition from Kerberos protocol
+```
+ AuthorizationData ::= SEQUENCE OF SEQUENCE {
+     ad-type         [0] Int32,
+     ad-data         [1] OCTET STRING
+ }
+ ```
+
+You can model AuthzDataEntry as follows
+```java
+public class AuthorizationDataEntry extends KrbSequenceType {
+    /**
+     * The possible fields
+     */
+    protected enum AuthorizationDataEntryField implements EnumType {
+        AD_TYPE,
+        AD_DATA;
+
+        /**
+         * {@inheritDoc}
+         */
+        @Override
+        public int getValue() {
+            return ordinal();
+        }
+
+        /**
+         * {@inheritDoc}
+         */
+        @Override
+        public String getName() {
+            return name();
+        }
+    }
+
+    /** The AuthorizationDataEntry's fields */
+    private static Asn1FieldInfo[] fieldInfos = new Asn1FieldInfo[] {
+            new ExplicitField(AuthorizationDataEntryField.AD_TYPE, Asn1Integer.class),
+            new ExplicitField(AuthorizationDataEntryField.AD_DATA, Asn1OctetString.class)
+    };
+
+    /**
+     * Creates an AuthorizationDataEntry instance
+     */
+    public AuthorizationDataEntry() {
+        super(fieldInfos);
+    }
+
+    /**
+     * @return The AuthorizationType (AD_TYPE) field
+     */
+    public AuthorizationType getAuthzType() {
+        Integer value = getFieldAsInteger(AuthorizationDataEntryField.AD_TYPE);
+        return AuthorizationType.fromValue(value);
+    }
+
+    /**
+     * Sets the AuthorizationType (AD_TYPE) field
+     * @param authzType The AuthorizationType to set
+     */
+    public void setAuthzType(AuthorizationType authzType) {
+        setFieldAsInt(AuthorizationDataEntryField.AD_TYPE, authzType.getValue());
+    }
+
+    /**
+     * @return The AuthorizationType (AD_DATA) field
+     */
+    public byte[] getAuthzData() {
+        return getFieldAsOctets(AuthorizationDataEntryField.AD_DATA);
+    }
+
+    /**
+     * Sets the AuthorizationData (AD_DATA) field
+     * @param authzData The AuthorizationData to set
+     */
+    public void setAuthzData(byte[] authzData) {
+        setFieldAsOctets(AuthorizationDataEntryField.AD_DATA, authzData);
+    }
+}
+```
+
+And then define AuthorizationData simply
+```java
+public class AuthorizationData extends KrbSequenceOfType<AuthorizationDataEntry> {
+
+}
+```
+
+Then you can process with above definitions, encode and decode, without caring about the
details.
+
+Think about how to implement the following more complex and pratical sample from [ITU-T Rec.
X.680 ISO/IEC 8824-1](http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf):
+```
+A.1 ASN.1 description of the record structure
+The structure of the hypothetical personnel record is formally described below using ASN.1
specified in
+ITU-T Rec. X.680 | ISO/IEC 8824-1 for defining types.
+
+PersonnelRecord ::= [APPLICATION 0] IMPLICIT SET {
+    Name Name,
+    title [0] VisibleString,
+    number EmployeeNumber,
+    dateOfHire [1] Date,
+    nameOfSpouse [2] Name,
+    children [3] IMPLICIT
+    SEQUENCE OF ChildInformation DEFAULT {}
+}
+
+ChildInformation ::= SET {
+    name Name,
+    dateOfBirth [0] Date
+}
+
+Name ::= [APPLICATION 1] IMPLICIT SEQUENCE {
+    givenName VisibleString,
+    initial VisibleString,
+    familyName VisibleString
+}
+
+EmployeeNumber ::= [APPLICATION 2] IMPLICIT INTEGER
+Date ::= [APPLICATION 3] IMPLICIT VisibleString -- YYYYMMDD
+```
+Similarly as above, we can have (from the unit test codes):
+```java
+public class PersonnelRecord extends Asn1TaggingSet {
+    protected enum PersonnelRecordField implements EnumType {
+        NAME,
+        TITLE,
+        NUMBER,
+        DATE_OF_HIRE,
+        NAME_OF_SPOUSE,
+        CHILDREN;
+
+        @Override
+        public int getValue() {
+            return ordinal();
+        }
+
+        @Override
+        public String getName() {
+            return name();
+        }
+    }
+
+    static Asn1FieldInfo[] fieldInfos = new Asn1FieldInfo[] {
+            new ExplicitField(PersonnelRecordField.NAME, -1, Name.class),
+            new ExplicitField(PersonnelRecordField.TITLE, 0, Asn1VisibleString.class),
+            new ExplicitField(PersonnelRecordField.NUMBER, -1, EmployeeNumber.class),
+            new ExplicitField(PersonnelRecordField.DATE_OF_HIRE, 1, Date.class),
+            new ExplicitField(PersonnelRecordField.NAME_OF_SPOUSE, 2, Name.class),
+            new ImplicitField(PersonnelRecordField.CHILDREN, 3, Children.class)
+    };
+
+    public PersonnelRecord() {
+        super(0, fieldInfos, true, true);
+    }
+
+    public void setName(Name name) {
+        setFieldAs(PersonnelRecordField.NAME, name);
+    }
+
+    public Name getName() {
+        return getFieldAs(PersonnelRecordField.NAME, Name.class);
+    }
+
+    public void setTitle(String title) {
+        setFieldAs(PersonnelRecordField.TITLE, new Asn1VisibleString(title));
+    }
+
+    public String getTitle() {
+        return getFieldAsString(PersonnelRecordField.TITLE);
+    }
+
+    public void setEmployeeNumber(EmployeeNumber employeeNumber) {
+        setFieldAs(PersonnelRecordField.NUMBER, employeeNumber);
+    }
+
+    public EmployeeNumber getEmployeeNumber() {
+        return getFieldAs(PersonnelRecordField.NUMBER, EmployeeNumber.class);
+    }
+
+    public void setDateOfHire(Date dateOfHire) {
+        setFieldAs(PersonnelRecordField.DATE_OF_HIRE, dateOfHire);
+    }
+
+    public Date getDateOfHire() {
+        return getFieldAs(PersonnelRecordField.DATE_OF_HIRE, Date.class);
+    }
+
+    public void setNameOfSpouse(Name spouse) {
+        setFieldAs(PersonnelRecordField.NAME_OF_SPOUSE, spouse);
+    }
+
+    public Name getNameOfSpouse() {
+        return getFieldAs(PersonnelRecordField.NAME_OF_SPOUSE, Name.class);
+    }
+
+    public void setChildren(Children children) {
+        setFieldAs(PersonnelRecordField.CHILDREN, children);
+    }
+
+    public Children getChildren() {
+        return getFieldAs(PersonnelRecordField.CHILDREN, Children.class);
+    }
+
+    public static class Children extends Asn1SequenceOf<ChildInformation> {
+        public Children(ChildInformation ... children) {
+            super();
+            for (ChildInformation child : children) {
+                addElement(child);
+            }
+        }
+
+        public Children() {
+            super();
+        }
+    }
+
+    public static class ChildInformation extends Asn1SetType {
+        protected enum ChildInformationField implements EnumType {
+            CHILD_NAME,
+            DATE_OF_BIRTH;
+
+            @Override
+            public int getValue() {
+                return ordinal();
+            }
+
+            @Override
+            public String getName() {
+                return name();
+            }
+        }
+
+        static Asn1FieldInfo[] tags = new Asn1FieldInfo[] {
+                new ExplicitField(ChildInformationField.CHILD_NAME, -1, Name.class),
+                new ExplicitField(ChildInformationField.DATE_OF_BIRTH, 0, Date.class)
+        };
+
+        public ChildInformation() {
+            super(tags);
+        }
+
+        public void setName(Name name) {
+            setFieldAs(ChildInformationField.CHILD_NAME, name);
+        }
+
+        public Name getName() {
+            return getFieldAs(ChildInformationField.CHILD_NAME, Name.class);
+        }
+
+        public void setDateOfBirth(Date date) {
+            setFieldAs(ChildInformationField.DATE_OF_BIRTH, date);
+        }
+
+        public Date getDateOfBirth() {
+            return getFieldAs(ChildInformationField.DATE_OF_BIRTH, Date.class);
+        }
+    }
+
+    public static class Name extends Asn1TaggingSequence {
+
+        protected enum NameField implements EnumType {
+            GIVENNAME,
+            INITIAL,
+            FAMILYNAME;
+
+            @Override
+            public int getValue() {
+                return ordinal();
+            }
+
+            @Override
+            public String getName() {
+                return name();
+            }
+        }
+
+        static Asn1FieldInfo[] tags = new Asn1FieldInfo[] {
+                new ExplicitField(NameField.GIVENNAME, -1, Asn1VisibleString.class),
+                new ExplicitField(NameField.INITIAL, -1, Asn1VisibleString.class),
+                new ExplicitField(NameField.FAMILYNAME, -1, Asn1VisibleString.class)
+        };
+
+        public Name() {
+            super(1, tags, true, true);
+        }
+
+        public Name(String givenName, String initial, String familyName) {
+            this();
+            setGivenName(givenName);
+            setInitial(initial);
+            setFamilyName(familyName);
+        }
+
+        public void setGivenName(String givenName) {
+            setFieldAs(NameField.GIVENNAME, new Asn1VisibleString(givenName));
+        }
+
+        public String getGivenName() {
+            return getFieldAsString(NameField.GIVENNAME);
+        }
+
+        public void setInitial(String initial) {
+            setFieldAs(NameField.INITIAL, new Asn1VisibleString(initial));
+        }
+
+        public String getInitial() {
+            return getFieldAsString(NameField.INITIAL);
+        }
+
+        public void setFamilyName(String familyName) {
+            setFieldAs(NameField.FAMILYNAME, new Asn1VisibleString(familyName));
+        }
+
+        public String getFamilyName() {
+            return getFieldAsString(NameField.FAMILYNAME);
+        }
+    }
+
+    public static class EmployeeNumber extends Asn1Tagging<Asn1Integer> {
+        public EmployeeNumber(Integer value) {
+            super(2, new Asn1Integer(value), true, true);
+        }
+
+        public EmployeeNumber() {
+            super(2, new Asn1Integer(), true, true);
+        }
+    }
+
+    public static class Date extends Asn1Tagging<Asn1VisibleString> {
+        public Date(String value) {
+            super(3, new Asn1VisibleString(value), true, true);
+        }
+        public Date() {
+            this(null);
+        }
+    }
+}
+```
+### Asn1 API and parsing/dumping facilities
+* ASN1 dumping tool to help analyze ASN1 encoding stream or packet. It can be used to exercise
the framework with all kinds of testing binary inputs.
+* The shortcut API for ASN1 parser, encoding, decoding.
+
+### Notes
+* Extensive tests coverage for BER & DER encoding and decoding
+* Fully self-contained, no extra dependency
+
+### License
+Apache V2 License
+

Modified: directory/site/trunk/content/kerby/user-guide.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/user-guide.mdtext?rev=1726932&r1=1726931&r2=1726932&view=diff
==============================================================================
--- directory/site/trunk/content/kerby/user-guide.mdtext (original)
+++ directory/site/trunk/content/kerby/user-guide.mdtext Wed Jan 27 01:49:34 2016
@@ -24,6 +24,10 @@ This is a simple guide to help users and
 
 * [1 - How to begin](user-guide/1-how-to-begin.html)
 * [2 - APIs](user-guide/2-kerberos-library.html)
+    * [2.1 - KrbClient APIs](user-guide/2.1-krbclient-apis.html)
+    * [2.2 - Kadmin](user-guide/2.2-kadmin.html)
+    * [2.3 - KdcServer](user-guide/2.3-kdcserver.html)
+    * [2.4 - SimpleKdcServer](user-guide/2.4-simplekdcserver.html)
 * [3 - Tools](user-guide/3-tools.html)
     * [3.1 - kdcinit](user-guide/3.1-kdcinit.html)
     * [3.2 - kadmin](user-guide/3.2-kadmin.html)

Modified: directory/site/trunk/content/kerby/user-guide/2-kerberos-library.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/user-guide/2-kerberos-library.mdtext?rev=1726932&r1=1726931&r2=1726932&view=diff
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/2-kerberos-library.mdtext (original)
+++ directory/site/trunk/content/kerby/user-guide/2-kerberos-library.mdtext Wed Jan 27 01:49:34
2016
@@ -3,8 +3,8 @@ NavPrev: 1-how-to-begin.html
 NavPrevtext: 1 - How To Begin
 NavUp: ../user-guide.html
 NavUpText: User Guide
-NavNext: 3-tools.html
-NavNextText: 3 - tools
+NavNext: 2.1-krbclient-apis.html
+NavNextText: 2.1 - KrbClient APIs
 Notice: Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
@@ -25,4 +25,12 @@ Notice: Licensed to the Apache Software
 # 2 - Kerberos library
 Kerby provides the KrbClient API, Kadmin API, Kerberos Server API and the simplified kdc
server APIs.
 
+## Table of content
+
+* [2.1 - KrbClient API](2.1-krbclient-apis.html)
+* [2.2 - Kadmin](2.2-kadmin.html)
+* [2.3 - KdcServer](2.3-kdcserver.html)
+* [2.4 - SimpleKdcServer](2.4-simplekdcserver.html)
+
+
 Please look at [github](https://github.com/apache/directory-kerby) for details.

Modified: directory/site/trunk/content/kerby/user-guide/2.2-kadmin.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/user-guide/2.2-kadmin.mdtext?rev=1726932&r1=1726931&r2=1726932&view=diff
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/2.2-kadmin.mdtext (original)
+++ directory/site/trunk/content/kerby/user-guide/2.2-kadmin.mdtext Wed Jan 27 01:49:34 2016
@@ -25,14 +25,21 @@ Notice: Licensed to the Apache Software
 # 2.2 - Kadmin
 Server side admin facilities.
 
-### Initiate a Kadmin
-* Initiate a Kadmin with confDir.
+
+
+## Local mode
+### Initiate a LocalKadminImpl
+* Initiate a LocalKadminImpl with prepared KdcConfig and BackendConfig.
 <pre>
-Kadmin kadmin = new Kadmin(confDir);
+LocalKadmin kadmin = new LocalKadminImpl(kdcConfig, backendConfig);
 </pre>
-* Initiate a Kadmin with kdcSetting and backend.
+* Initiate a LocalKadmin with confDir.
 <pre>
-Kadmin kadmin = new Kadmin(kdcSetting, backend);
+LocalKadmin kadmin = new LocalKadminImpl(confDir);
+</pre>
+* Initiate a LocalKadmin with kdcSetting and backend.
+<pre>
+LocalKadmin kadmin = new LocalKadminImpl(kdcSetting, backend);
 </pre>
 
 ### Principal operating
@@ -81,3 +88,4 @@ updatePassword(principal, newPassword);
 exportKeyTab(keyTabFile);
 </pre>
 
+

Modified: directory/site/trunk/content/kerby/user-guide/2.3-kdcserver.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/user-guide/2.3-kdcserver.mdtext?rev=1726932&r1=1726931&r2=1726932&view=diff
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/2.3-kdcserver.mdtext (original)
+++ directory/site/trunk/content/kerby/user-guide/2.3-kdcserver.mdtext Wed Jan 27 01:49:34
2016
@@ -25,6 +25,8 @@ Notice: Licensed to the Apache Software
 # 2.3 - KdcServer
 Kerberos Server API.
 
+
+
 ### Initiate kdc server
 * Initiate a kdc server with prepared confDir.
 <pre>
@@ -70,7 +72,7 @@ setInnerKdcImpl(innerKdcImpl);
 </pre>
 
 ### Stop kdc server
-* Stop kdc server.
+* Start kdc server.
 <pre>
 stop();
 </pre>

Modified: directory/site/trunk/content/kerby/user-guide/2.4-simplekdcserver.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/user-guide/2.4-simplekdcserver.mdtext?rev=1726932&r1=1726931&r2=1726932&view=diff
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/2.4-simplekdcserver.mdtext (original)
+++ directory/site/trunk/content/kerby/user-guide/2.4-simplekdcserver.mdtext Wed Jan 27 01:49:34
2016
@@ -25,8 +25,8 @@ Notice: Licensed to the Apache Software
 # 2.4 - SimpleKdcServer
 A simplified Kdc server. It can be imported by other project to work as a kdc server.
 
-## Kdc server
-
+### Kdc server
+</pre>
 * Start simple kdc server.
 <pre>
 start();
@@ -54,10 +54,9 @@ setAllowTcp(allowTcp);
 * Set to allow UDP or not.
 <pre>
 setAllowUdp(allowUdp);
-</pre>
-
-## Kadmin
 
+### Kadmin
+</pre>
 * Create principle with principal name.
 <pre>
 createPrincipal(principal);
@@ -78,12 +77,15 @@ createAndExportPrincipals(keytabFile pri
 <pre>
 deletePrincipal(principal);
 </pre>
+</pre>
 * Delete principles with principal names.
 <pre>
 deletePrincipals(principals);
 </pre>
+</pre>
 * Export principles to keytab file.
 <pre>
 exportPrincipals(keytabFile);
 </pre>
 
+

Modified: directory/site/trunk/templates/kerby/page.html
URL: http://svn.apache.org/viewvc/directory/site/trunk/templates/kerby/page.html?rev=1726932&r1=1726931&r2=1726932&view=diff
==============================================================================
--- directory/site/trunk/templates/kerby/page.html (original)
+++ directory/site/trunk/templates/kerby/page.html Wed Jan 27 01:49:34 2016
@@ -29,6 +29,7 @@
     <ul>
         <li><a href="{{base}}kerby/overview.html">Overview</a></li>
 	 <!--li><a href="{{base}}kerby/quick-start.html">Quick Start</a></li-->
+        <li><a href="{{base}}kerby/kerby-asn1.html">Kerby ASN1</a></li>
         <li><a href="{{base}}kerby/user-guide.html">User Guide</a></li>
         <!--li><a href="{{base}}kerby/gen-docs/latest/apidocs/">JavaDocs</a></li-->
         <!--li><a href="{{base}}kerby/gen-docs/latest/xref/">Cross-Reference</a></li-->



Mime
View raw message