You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by pl...@apache.org on 2015/07/06 10:23:38 UTC
svn commit: r1689334 - in /directory/site/trunk/content/kerby: ./ user-guide/
Author: plusplusjiajia
Date: Mon Jul 6 08:23:37 2015
New Revision: 1689334
URL: http://svn.apache.org/r1689334
Log:
Add the content of overview, quick-start and user-guide.
Added:
directory/site/trunk/content/kerby/user-guide/
directory/site/trunk/content/kerby/user-guide/1-how-to-begin.mdtext
directory/site/trunk/content/kerby/user-guide/2-apis.mdtext
directory/site/trunk/content/kerby/user-guide/2.1-krbclient-apis.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
Modified:
directory/site/trunk/content/kerby/overview.mdtext
directory/site/trunk/content/kerby/quick-start.mdtext
directory/site/trunk/content/kerby/user-guide.mdtext
Modified: directory/site/trunk/content/kerby/overview.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/overview.mdtext?rev=1689334&r1=1689333&r2=1689334&view=diff
==============================================================================
--- directory/site/trunk/content/kerby/overview.mdtext (original)
+++ directory/site/trunk/content/kerby/overview.mdtext Mon Jul 6 08:23:37 2015
@@ -18,8 +18,15 @@ Notice: Licensed to the Apache Software
# Kerby Overview
-## Rationale
-
-
-## What is it?
+## The Initiatives/Goals
+*Aims as a Java Kerberos binding, with rich and integrated facilities that integrate Kerberos, PKI and token (OAuth2) for both client and server sides.
+*Provides client APIs at the Kerberos protocol level to interact with a KDC server through AS and TGS exchanges.
+*Provides a standalone KDC server that supports various identity back ends including memory based, Json file based, LDAP backed and even Zookeeper backed.
+*Provides an embedded KDC server that applications can easily integrate into products, unit tests or integration tests.
+*Supports FAST/Preauthentication framework to allow popular and useful authentication mechanisms.
+*Supports PKINIT mechanism to allow clients to request tickets using x509 certificate credentials.
+*Supports Token Preauth mechanism to allow clients to request tickets using JWT tokens.
+*Supports OTP mechanism to allow clients to request tickets using One Time Password.
+*Provides support for JAAS, GSSAPI and SASL frameworks that applications can leverage.
+*Minimal dependencies, the core part is ensured to depend only on JRE and SLF4J, for easy use and maintenance.
Modified: directory/site/trunk/content/kerby/quick-start.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/quick-start.mdtext?rev=1689334&r1=1689333&r2=1689334&view=diff
==============================================================================
--- directory/site/trunk/content/kerby/quick-start.mdtext (original)
+++ directory/site/trunk/content/kerby/quick-start.mdtext Mon Jul 6 08:23:37 2015
@@ -20,3 +20,57 @@ Notice: Licensed to the Apache Software
The Quick Start guides show you how to do base install of Kerby:
+## 1. How to play with the standalone KDC:
+
+The distribution of Kerby.
+
+### To run with a standalone kdc server, kinit and kadmin
+
+* Generate libraries for distribution:
+```
+mvn package -Pdist
+```
+
+* Run kadmin to add principals:
+```
+sh kerby-dist/tool-dist/bin/kadmin.sh [server-conf-dir]
+```
+
+ In kadmin, you can type "?" for help. For now, the kadmin only supports to add principals to json-backend. (Working in progress).
+
+* Start kerby-kdc-server:
+```
+sh kerby-dist/kdc-dist/bin/start-kdc.sh Âstart [server-conf-dir] [work-dir]
+```
+
+* Run kinit:
+```
+sh kerby-dist/tool-dist/bin/kinit.sh [principal-name]
+```
+
+ If you don't specify [server-conf-dir] in step 2 or 3, it will be set as /etc/kerby. In [server-conf-dir], there should be kdc.conf, backend.conf. And in /etc/, there should be krb5.conf.
+
+An example of kdc.conf:
+```
+[kdcdefaults]
+ kdc_host = localhost
+ kdc_tcp_port = 8015
+ kdc_realm = TEST.COM
+```
+An example of json backend backend.conf:
+```
+kdc_identity_backend = org.apache.kerby.kerberos.kdc.identitybackend.JsonIdentityBackend
+backend.json.file = /tmp/kerby/jsonbackend
+```
+An example of zookeeper backend backend.conf:
+```
+kdc_identity_backend = org.apache.kerby.kerberos.kdc.identitybackend.ZookeeperIdentityBackend
+data_dir = /tmp/kerby/zookeeper/data
+data_log_dir = /tmp/kerby/zookeeper/datalog
+```
+An example of krb5.conf:
+```
+[libdefaults]
+ kdc_realm=TEST.COM
+```
+
Modified: directory/site/trunk/content/kerby/user-guide.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/user-guide.mdtext?rev=1689334&r1=1689333&r2=1689334&view=diff
==============================================================================
--- directory/site/trunk/content/kerby/user-guide.mdtext (original)
+++ directory/site/trunk/content/kerby/user-guide.mdtext Mon Jul 6 08:23:37 2015
@@ -25,3 +25,9 @@ This guide is primarily for people new t
## Table of contents
+* [1 - How to begin](user-guide/1-how-to-begin.html)
+* [2 - APIs](basic-ug/2-apis.html)
+ * [2.1 - KrbClient APIs](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)
Added: directory/site/trunk/content/kerby/user-guide/1-how-to-begin.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/user-guide/1-how-to-begin.mdtext?rev=1689334&view=auto
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/1-how-to-begin.mdtext (added)
+++ directory/site/trunk/content/kerby/user-guide/1-how-to-begin.mdtext Mon Jul 6 08:23:37 2015
@@ -0,0 +1,26 @@
+Title: 1 - How To Begin
+NavUp: ../user-guide.html
+NavUpText: Basic User Guide
+NavNext: 2-apis.html
+NavNextText: 2 - 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
+ 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.
+
+# 1 - How to begin
+This chapter helps you to set up a server, with the minimal configuration options being explained. That should be enough to get a running server.
+
+## Table of content
Added: directory/site/trunk/content/kerby/user-guide/2-apis.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/user-guide/2-apis.mdtext?rev=1689334&view=auto
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/2-apis.mdtext (added)
+++ directory/site/trunk/content/kerby/user-guide/2-apis.mdtext Mon Jul 6 08:23:37 2015
@@ -0,0 +1,33 @@
+Title: 2 - APIs
+NavUp: ../basic-user-guide.html
+NavUpText: Basic User Guide
+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
+ 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.
+
+# 2 - APIs
+This chapter helps you to set up a server, with the minimal configuration options being explained. That should be enough to get a running server.
+
+This user guide is **not** intended to be a **LDAP** guide : there are some excellent tutorials or books, we won't try to challenge them !
+
+## Table of content
+
+* [2.1 - KrbClient APIs](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)
\ No newline at end of file
Added: directory/site/trunk/content/kerby/user-guide/2.1-krbclient-apis.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/kerby/user-guide/2.1-krbclient-apis.mdtext?rev=1689334&view=auto
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/2.1-krbclient-apis.mdtext (added)
+++ directory/site/trunk/content/kerby/user-guide/2.1-krbclient-apis.mdtext Mon Jul 6 08:23:37 2015
@@ -0,0 +1,56 @@
+Title: 2.1 - KrbClient APIs
+NavPrev: 2-apis.html
+NavPrevText: 2 - APIs
+NavUp: 2-apis.html
+NavUpText: 2 - APIs
+NavNext: 2.2-kadmin.html
+NavNextText: 2.2 - Kadmin
+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.
+
+kerb-client
+============
+
+### Initiate a KrbClient
+* Initiate a KrbClient with prepared KrbConfig.
+<pre>
+KrbClient krbClient = new KrbClient(krbConfig);
+</pre>
+* Initiate a KrbClient with with conf dir.
+<pre>
+KrbClient krbClient = new KrbClient(confDir);
+</pre>
+
+### Request a TGT
+* Request a TGT with user plain password credential
+<pre>
+requestTgtWithPassword(principal, password);
+</pre>
+* Request a TGT with user token credential
+<pre>
+requestTgtWithToken(token, armorCache);
+</pre>
+
+### Request a service ticket
+* Request a service ticket with user TGT credential for a server
+<pre>
+requestServiceTicketWithTgt(tgt, serverPrincipal);
+</pre>
+* Request a service ticket with user AccessToken credential for a server
+<pre>
+requestServiceTicketWithAccessToken(accessToken, serverPrincipal, armorCache);
+</pre>
Added: 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=1689334&view=auto
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/2.2-kadmin.mdtext (added)
+++ directory/site/trunk/content/kerby/user-guide/2.2-kadmin.mdtext Mon Jul 6 08:23:37 2015
@@ -0,0 +1,83 @@
+Title: 2.2 - Kadmin
+NavPrev: 2.1-krbclient-apis.html
+NavPrevText: 2.1 - KrbClient APIs
+NavUp: 2.1-krbclient-apis.html
+NavUpText: 2.1 - KrbClient APIs
+NavNext: 2.3-kdcserver.html
+NavNextText: 2.3 - KdcServer
+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.
+
+kerb-admin
+============
+
+### Initiate a Kadmin
+* Initiate a Kadmin with confDir.
+<pre>
+Kadmin kadmin = new Kadmin(confDir);
+</pre>
+* Initiate a Kadmin with kdcSetting and backend.
+<pre>
+Kadmin kadmin = new Kadmin(kdcSetting, backend);
+</pre>
+
+### Principal operating
+* Add principle with principal name.
+<pre>
+addPrincipal(principal);
+</pre>
+* Add principle with principal name and password.
+<pre>
+addPrincipal(principal, password);
+</pre>
+* Add principle with principal name and kOptions.
+<pre>
+addPrincipal(principal, kOptions);
+</pre>
+* Add principle with principal name, password and kOptions.
+<pre>
+addPrincipal(principal, password kOptions);
+</pre>
+* Delete principle with principal name.
+<pre>
+deletePrincipal(principal);
+</pre>
+* Modify principle with principal name and kOptions.
+<pre>
+modifyPrincipal(principal, kOptions);
+</pre>
+* Rename principle.
+<pre>
+renamePrincipal(oldPrincipalName, newPrincipalName);
+</pre>
+* Get principle with principal name.
+<pre>
+getPrincipal(principalName);
+</pre>
+* Get all the principles.
+<pre>
+getPrincipals();
+</pre>
+* Update password with principal name and new password.
+<pre>
+updatePassword(principal, newPassword);
+</pre>
+* Export all identity keys to the specified keytab file.
+<pre>
+exportKeyTab(keyTabFile);
+</pre>
+
Added: 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=1689334&view=auto
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/2.3-kdcserver.mdtext (added)
+++ directory/site/trunk/content/kerby/user-guide/2.3-kdcserver.mdtext Mon Jul 6 08:23:37 2015
@@ -0,0 +1,76 @@
+Title: 2.3 - KdcServer
+NavPrev: 2.2-kadmin.html
+NavPrevText: 2.2 - Kadmin
+NavUp: 2.2-kadmin.html
+NavUpText: 2.2 - Kadmin
+NavNext: 2.3-kdcserver.html
+NavNextText: 2.4 - SimpleKdcServer
+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.
+
+kerb-server
+============
+
+### Initiate kdc server
+* Initiate a kdc server with prepared confDir.
+<pre>
+KdcServer server = new KdcServer(confDir);
+</pre>
+
+### Start and set kdc server
+* Start kdc server.
+<pre>
+start();
+</pre>
+* Set KDC realm for ticket request
+<pre>
+setKdcRealm(realm);
+</pre>
+* Set KDC host.
+<pre>
+setKdcHost(kdcHost);
+</pre>
+* Set KDC tcp port.
+<pre>
+setKdcTcpPort(kdcTcpPort);
+</pre>
+* Set KDC udp port. Only makes sense when allowUdp is set.
+<pre>
+setKdcUdpPort(kdcUdpPort);
+</pre>
+* Set to allow TCP or not.
+<pre>
+setAllowTcp(allowTcp);
+</pre>
+* Set to allow UDP or not.
+<pre>
+setAllowUdp(allowUdp);
+</pre>
+* Allow to debug so have more logs.
+<pre>
+enableDebug();
+</pre>
+* Allow to hook customized kdc implementation.
+<pre>
+setInnerKdcImpl(innerKdcImpl);
+</pre>
+
+### Stop kdc server
+* Start kdc server.
+<pre>
+stop();
+</pre>
Added: 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=1689334&view=auto
==============================================================================
--- directory/site/trunk/content/kerby/user-guide/2.4-simplekdcserver.mdtext (added)
+++ directory/site/trunk/content/kerby/user-guide/2.4-simplekdcserver.mdtext Mon Jul 6 08:23:37 2015
@@ -0,0 +1,90 @@
+Title: 2.4 - SimpleKdcServer
+NavPrev: 2.3-kdcserver.html
+NavPrevText: 2.3 - KdcServer
+NavUp: 2.3-kdcserver.html
+NavUpText: 2.3 - KdcServer
+NavNext: 2.3-kdcserver.html
+NavNextText: 2.4 - SimpleKdcServer
+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.
+
+kerb-simplekdc
+============
+
+### Kdc server
+</pre>
+* Start simple kdc server.
+<pre>
+start();
+</pre>
+* Set KDC realm for ticket request
+<pre>
+setKdcRealm(realm);
+</pre>
+* Set KDC host.
+<pre>
+setKdcHost(kdcHost);
+</pre>
+* Set KDC tcp port.
+<pre>
+setKdcTcpPort(kdcTcpPort);
+</pre>
+* Set KDC udp port. Only makes sense when allowUdp is set.
+<pre>
+setKdcUdpPort(kdcUdpPort);
+</pre>
+* Set to allow TCP or not.
+<pre>
+setAllowTcp(allowTcp);
+</pre>
+* Set to allow UDP or not.
+<pre>
+setAllowUdp(allowUdp);
+
+### Kadmin
+</pre>
+* Create principle with principal name.
+<pre>
+createPrincipal(principal);
+</pre>
+* Add principle with principal name and password.
+<pre>
+createPrincipal(principal, password);
+</pre>
+* Create principles with principal names.
+<pre>
+createPrincipals(principals);
+</pre>
+* Creates principals and export their keys to the specified keytab file.
+<pre>
+createAndExportPrincipals(keytabFile principals);
+</pre>
+* Delete principle with principal name.
+<pre>
+deletePrincipal(principal);
+</pre>
+</pre>
+* Delete principles with principal names.
+<pre>
+deletePrincipals(principals);
+</pre>
+</pre>
+* Export principles to keytab file.
+<pre>
+exportPrincipals(keytabFile);
+</pre>
+