Adaptive Server® Anywhere Authenticated Edition Read Me First

No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.

Sybase, SYBASE (logo), AccelaTrade, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server, Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication, Adaptive Server Everywhere, Adaptive Server IQ, Adaptive Warehouse, AnswerBase, Anywhere Studio, Application Manager, AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-Library, APT-Translator, ASEP, AvantGo, AvantGo Application Alerts, AvantGo Mobile Delivery, AvantGo Mobile Document Viewer, AvantGo Mobile Inspection, AvantGo Mobile Marketing Channel, AvantGo Mobile Pharma, AvantGo Mobile Sales, AvantGo Pylon, AvantGo Pylon Application Server, AvantGo Pylon Conduit, AvantGo Pylon PIM Server, AvantGo Pylon Pro, Backup Server, BayCam, Bit-Wise, BizTracker, Certified PowerBuilder Developer, Certified SYBASE Professional, Certified SYBASE Professional (logo), ClearConnect, Client Services, Client-Library, CodeBank, Column Design, ComponentPack, Connection Manager, Convoy/DM, Copernicus, CSP, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress, DataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, Distribution Director, Dynamic Mobility Model, Dynamo, e-ADK, E-Anywhere, e-Biz Integrator, E-Whatever, EC Gateway, ECMAP, ECRTP, eFulfillment Accelerator, Electronic Case Management, Embedded SQL, EMS, Enterprise Application Studio, Enterprise Client/Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise Portal (logo), Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work Designer, Enterprise Work Modeler, eProcurement Accelerator, eremote, Everything Works Better When Everything Works Together, EWA, Financial Fusion, Financial Fusion (and design), Financial Fusion Server, Formula One, Fusion Powered e-Finance, Fusion Powered Financial Destinations, Fusion Powered STP, Gateway Manager, GeoPoint, GlobalFIX, iAnywhere, iAnywhere Solutions, ImpactNow, Industry Warehouse Studio, InfoMaker, Information Anywhere, Information Everywhere, InformationConnect, InstaHelp, Intelligent Self-Care, InternetBuilder, iremote, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBase, Logical Memory Manager, M-Business Channel, M-Business Network, M-Business Server, Mail Anywhere Studio, MainframeConnect, Maintenance Express, Manage Anywhere Studio, MAP, MDI Access Server, MDI Database Gateway, media.splash, Message Anywhere Server, MetaWorks, MethodSet, ML Query, MobiCATS, My AvantGo, My AvantGo Media Channel, My AvantGo Mobile Marketing, MySupport, Net-Gateway, Net-Library, New Era of Networks, Next Generation Learning, Next Generation Learning Studio, O DEVICE, OASiS, OASiS (logo), ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Biz, Open Business Interchange, Open Client, Open Client/Server, Open Client/Server Interfaces, Open ClientConnect, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, Orchestration Studio, Partnerships that Work, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library, PhysicalArchitect, Pocket PowerBuilder, PocketBuilder, Power Through Knowledge, Power++, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, Powering the New Economy, PowerJ, PowerScript, PowerSite, PowerSocket, Powersoft, Powersoft Portfolio, Powersoft Professional, PowerStage, PowerStudio, PowerTips, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst, QAnywhere, Rapport, Relational Beans, RepConnector, Replication Agent, Replication Driver, Replication Server, Replication Server Manager, Replication Toolkit, Report Workbench, Report-Execute, Resource Manager, RW-DisplayLib, RW-Library, S.W.I.F.T. Message Format Libraries, SAFE, SAFE/PRO, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script, SQL Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL Server SNMP SubAgent, SQL Server/CFT, SQL Server/DBM, SQL SMART, SQL Station, SQL Toolset, SQLJ, Stage III Engineering, Startup.Com, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase Development Framework, Sybase Financial Server, Sybase Gateways, Sybase Learning Connection, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase Synergy Program, Sybase User Workbench, Sybase Virtual Server Architecture, SybaseWare, Syber Financial, SyberAssist, SybMD, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, The Enterprise Client/Server Company, The Extensible Software Platform, The Future Is Wide Open, The Learning Connection, The Model For Client/Server Solutions, The Online Information Center, The Power of One, TotalFix, TradeForce, Transact-SQL, Translation Toolkit, Turning Imagination Into Reality, UltraLite, UltraLite.NET, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Versacore, Viewer, VisualWriter, VQL, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, WarehouseArchitect, Watcom, Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server, and XP Server are trademarks of Sybase, Inc. or its subsidiaries.

All other trademarks are property of their respective owners.

ii Contents

About This Manual v

1 OEM Edition Read Me First 1 Authenticated Adaptive Server Anywhere applications . . . . 2 Developing an authenticated application ...... 5

iii iv About This Manual

Subject This booklet describes the OEM Edition of Adaptive Server Anywhere. It describes the tools you need to use authentication, and addresses issues of developing authenticated applications. Audience This manual is for anyone building applications with the OEM Edition of Adaptive Server Anywhere.

v vi CHAPTER 1

OEM Edition Read Me First

About this booklet This booklet describes how to use the OEM Edition of Adaptive Server Anywhere.

Contents Topic: page

Authenticated Adaptive Server Anywhere applications 2

Developing an authenticated application 5

1 Authenticated Adaptive Server Anywhere applications

The OEM Edition of Adaptive Server Anywhere is provided for Sybase OEM Partners. With the OEM Edition, applications that are not authenticated are limited in the functions they can carry out. Database applications carry out a well-deﬁned set of operations against a database. With the OEM Edition of Adaptive Server Anywhere, applications other than those you supply are restricted in the operations they can perform. These limitations are in addition to any imposed through the SQL permission scheme. An authenticated application can carry out any operation on the database, subject to the permissions granted to the user ID. Note that unauthenticated connections can perform inserts, updates, and deletes on temporary tables. This allows complex reports to be created using stored procedures, and accessed using reporting tools, such as Crystal Reports. The authentication mechanism is independent of application programming language or tool, and is carried out on every connection. This means you can use both authenticated connections and more restricted unauthenticated connections in your application.

Authentication is not a security device Authentication is not a security mechanism. For example, anyone running an unauthenticated database server against the database can carry out any operation, subject to the usual SQL permissions scheme.

What you need for authentication

Developing an authenticated application is a simple process. A special authentication signature is incorporated into the database. A second signature is incorporated into your application. When the application connects to the database, the signatures are compared in order to authenticate the application. Working with the OEM Edition requires the following steps: 1. Use the authenticated database server The authenticated database server is the version included in this package.

2. Obtain authentication signatures The authentication mechanism relies on signatures obtained from Sybase.

2 Chapter 1. OEM Edition Read Me First

3. Create an authenticated database Authenticated databases are protected from unauthenticated applications.

4. Create an authenticated application You must add instructions to your application that authenticate it whenever it connects to the database. ☞ For a detailed description of each of these steps, see “Developing an authenticated application” on page 5.

Database tools are self-authenticating

All the database tools included with SQL Anywhere Studio, including Sybase Central, Interactive SQL, and the command-line utilities, are self-authenticating. This means that they are unrestricted in their operations against any authenticated database. If the database itself is not authenticated, the tools act in a restricted, read-only fashion. Self-authentication enables you to use dbbackup, for example, to back up an authenticated database running on an authenticated database server.

Upgrading authenticated databases

If you apply the Upgrade utility to an authenticated database, the authentication information is lost. If you store the authentication statement in the file saopts.sql, as described in “Step 3: Authenticate your database” on page 5, the authentication information is preserved on upgrading. If you want access to all the new features of SQL Anywhere Studio 9, including those such as new indexing features, procedure profiling, and Java 2 support which depend on database file storage, you must unload and reload your database. Again, adding the authentication statement to saopts.sql ensures that the authentication information is maintained. Storing the The saopts.sql file is found in the following location: C:\Program authentication string in Files\Sybase\SQL Anywhere 9\scripts. In the saopts.sql file, the section you the saopts.sql file edit is:

if not exists( SELECT * FROM SYS.SYSOPTION WHERE ucase( "option" ) = ucase( ’Database_authentication’ ) ) THEN SET OPTION PUBLIC.Database_authentication = ’’;

Once you add the authentication statement, your saopts.sql ﬁle should look like the following:

3 if not exists( SELECT * FROM SYS.SYSOPTION WHERE ucase( "option" ) = ucase( ’Database_authentication’ ) ) THEN SET OPTION PUBLIC.Database_authentication = ’your authentication statement here’;

4 Chapter 1. OEM Edition Read Me First

Developing an authenticated application

This section describes the steps involved in creating an authenticated application.

Step 1: Use the authenticated database server

The edition of the database server provided in this package is the OEM Edition. This edition differs from the usual database server only in that it processes authentication instructions. The authentication instructions are ignored by other editions of the database server. If you do not use the authenticated database server, no restrictions are placed on unauthenticated applications.

Step 2: Obtain authentication signatures

❖ To obtain your authentication signatures 1. Open the following URL in your web browser: http://www.sybase.com/products/anywhere/authentication 2. Click Go To The Online Form Now. 3. Complete the form to obtain your authentication signatures. The following information is incorporated into your authentication mechanism: ♦ Company name The name of your company. ♦ Application name The name of your application. ☞ For information about how the company name and application name are incorporated into the authentication mechanism, see “Step 3: Authenticate your database” on page 5. When you complete the form, you will be provided (by e-mail) with a database signature and an application signature within 48 hours. These signatures are long (81 character) strings of characters and digits. The e-mail message containing your authentication information includes some examples of how to use the information. Some e-mail systems force line breaks in these instructions. You should be sure to rejoin lines broken in the e-mail message if the instructions are to work.

Step 3: Authenticate your database

The OEM Edition of Adaptive Server Anywhere does not permit any operations to be carried out on an unauthenticated database.

5 ❖ To authenticate a database 1. Set the DATABASE_AUTHENTICATION option for the database, using the following SQL authentication statement: SET OPTION PUBLIC.DATABASE_AUTHENTICATION = ’company = company_name; application = application_name; signature = database_signature’ The company_name and application_name arguments are the values you supplied to Sybase when obtaining your signature, and database_signature is the database signature that you received from Sybase. 2. Restart the database for the option to take effect. When the database server loads an authenticated database, it displays a message in the database server window describing the authenticated company and application. You can check that this message is present to verify that the DATABASE_AUTHENTICATION option has taken effect. The message has the following form: This database is licensed for use with: Application: application_name Company: company_name

You can store the authentication statement in a SQL script file to avoid having to type in the long signature. You can run the SQL script from Interactive SQL by choosing Run Script from the File menu. If you store the authentication statement in the file saopts.sql, in the scripts subdirectory of your Adaptive Server Anywhere directory, it is applied whenever you create a database or upgrade a database. ☞ For instructions on storing the authentication statement in the saopts.sql file, see “Developing an authenticated application” on page 5.

Step 4: Authenticate your application

An authenticated application must set the CONNECTION_AUTHENTICATION database option immediately after connecting. The option must be set on every connection immediately after the connection is established. ODBC or JDBC applications query the database about its capabilities, and the developer may not have control over these actions. For this reason, every connection has a thirty second grace period before the restrictions apply. The grace period allows an application to authenticate regardless of which development tool is being used.

6 Chapter 1. OEM Edition Read Me First

The following SQL statement authenticates the connection: SET TEMPORARY OPTION CONNECTION_AUTHENTICATION = ’company = company_name; application = application_name; signature = application_signature’

The option must be set for the duration of the connection only using the TEMPORARY keyword. The company name and application name must match those in the database authentication statement. The signature is the application signature that you have obtained from Sybase. The database server verifies the application signature against the database signature. If the signature is verified, the connection is authenticated and has no restrictions on its activities beyond those assigned to its user ID. If the signature is not verified, the connection is limited to those actions permitted by unauthenticated applications. Executing the The way you execute the SET TEMPORARY OPTION statement that sets authentication statement the authentication option depends on the programming interface you are using. This section describes how to set the option using the ODBC, PowerBuilder, JDBC, and Embedded SQL interfaces. The signatures listed here are not valid signatures. ♦ ODBC Use the following statement:

SQLExecDirect(hstmt,"SET TEMPORARY OPTION CONNECTION_ AUTHENTICATION =’Company=MyCo;Application=MyApp;Signature=0fa55159 999e14d818eb4fe3db41447146f1571g0c4429e41262995f8cd ac5falkd3729c4a9afdaf’",SQL_NTS); The string must be entered on a single line or you must build it up by concatenation.

♦ PowerBuilder Use the following PowerScript statement:

EXECUTE IMMEDIATE "set temporary option ... " USING SQLCA

♦ JDBC Use the following statement:

Statement Stmt1 = con.createStatement(); Stmt1.executeUpdate("SET TEMPORARY OPTION CONNECTION_ AUTHENTICATION=’Company=MyCo;Application=MyApp;Sign ature=0fa55159999e14d818eb4fe3db41447146f1571g0c442 9e41262995f8cdac5falkd3729c4a9afdaf’"); The string must be entered on a single line or you must build it up by concatenation.

7 ♦ Embedded SQL Use the following statement: EXEC SQL SET TEMPORARY OPTION CONNECTION_AUTHENTICATION =’Company=MyCo;Application=MyApp;Signature=0fa55159 9998e14d818eb4fe3db41447146f1571g0c4429e41262995f8c dac5falkd3729c4a9afdaf’ The string must be entered on a single line or you must build it up by concatenation.

Using special characters in the authentication option

If your company name has quotation marks, apostrophes, or other special characters (for example, Joe’s Garage) you need to be careful about how you construct the authentication statement. The entire set of authentication options (Company=. . . ,Application=. . . ,Signature=. . . ) is a SQL string. The rules for strings in SQL dictate that if you include a quotation mark inside the string, it must be doubled in order to be accepted. For example: SET TEMPORARY OPTION CONNECTION_AUTHENTICATION = ’company = Joe’’s Garage; application = Joe’’s Program; signature = 0fa55157edb8e14d818e...’